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Foreword 



This Technical Specification has been produced by the 3 r Generation Partnership Project (3GPP). 

3GPP acknowledges the contribution of the Parlay X Web Services specifications from The Parlay Group. The Parlay 
Group is pleased to see 3GPP acknowledge and publish the present document, and the Parlay Group looks forward to 
working with the 3GPP community to improve future versions of the present document. 

The contents of the present document are subject to continuing work within the TSG and may change following formal 
TSG approval. Should the TSG modify the contents of the present document, it will be re-released by the TSG with an 
identifying change of release date and an increase in version number as follows: 

Version x.y.z 

where: 

x the first digit: 

1 presented to TSG for information; 

2 presented to TSG for approval; 

3 or greater indicates TSG approved document under change control. 

y the second digit is incremented for all changes of substance, i.e. technical enhancements, corrections, 
updates, etc. 

z the third digit is incremented when editorial only changes have been incorporated in the document. 



Introduction 



The present document is part 5 of a multi-part deliverable covering the 3 r Generation Partnership Project; Technical 
Specification Group Core Network and Terminals; Open Service Access (OSA); Parlay X Web Services, as identified 
below: 



Part 1: 


"Overview and common data definitions" 


Part 2: 


"Third party call"; 


Part 3: 


"Call Notification"; 


Part 4: 


"Short Messaging"; 


Part 5: 


"Multimedia Messaging"; 


Part 6: 


"Payment"; 


Part 7: 


"Account management"; 


Part 8: 


"Terminal Status"; 


Part 9: 


"Terminal location"; 


Part 10: 


"Call handling"; 


Part 11: 


"Audio call"; 


Part 12: 


"Multimedia conference"; 


Part 13: 


"Address list management"; 


Part 14: 


"Presence". 
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Scope 



The present document is Part 5 of the Stage 3 Parlay X Web Services specification for Open Service Access (OS A). 

The OS A specifications define an architecture that enables application developers to make use of network functionality 
through an open standardized interface, i.e. the OSA APIs. The concepts and the functional architecture for the OSA are 
contained in 3GPP TS 23.198 [3]. The requirements for OSA are contained in 3GPP TS 22.127 [2]. 

The present document specifies the Multimedia Messaging Web Service aspects of the interface. All aspects of the 
Multimedia Messaging Web Service are defined here, these being: 

Name spaces. 

Sequence diagrams. 

Data definitions. 

Interface specification plus detailed method descriptions. 

Fault definitions. 

Service policies. 

WSDL Description of the interfaces. 

The present document has been defined jointly between 3GPP TSG CT WG5, ETSI TISPAN and The Parlay Group. 



References 



The following documents contain provisions which, through reference in this text, constitute provisions of the present 
document. 

• References are either specific (identified by date of publication, edition number, version number, etc.) or 
non-specific. 

• For a specific reference, subsequent revisions do not apply. 

• For a non-specific reference, the latest version applies. In the case of a reference to a 3GPP document (including 
a GSM document), a non-specific reference implicitly refers to the latest version of that document in the same 
Release as the present document. 

[1] 3GPP TR 21.905: "Vocabulary for 3GPP Specifications". 

[2] 3GPP TS 22. 127: "Service Requirement for the Open Services Access (OSA); Stage 1 ". 

[3] 3GPP TS 23.198: "Open Service Access (OSA); Stage 2". 

[4] 3GPP TS 22.101: "Service aspects; Service principles". 

[5] W3C Recommendation (2 May 2001): "XML Schema Part 2: Datatypes". 

NOTE: Available at http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/ . 

[6] 3GPP TS 29.199-1: "Open Service Access (OSA); Parlay X Web Services; Part 1: Common". 

[7] W3C Note (11 December 2001): "SOAP Messages with Attachments". 

NOTE: Available at http://www.w3.org/TR/SOAP-attachments . 

[8] 3GPP TS 23.140 "Multimedia Messaging Service (MMS); Functional description; Stage 2". 

[9] RFC2822: "Internet Message Format". 

NOTE: Available at http://www.ietf.org/rfc/rfc2822.txt 
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Definitions and abbreviations 



3.1 Definitions 

For the purposes of the present document, the terms and definitions given in 3GPP TS 29.199-1 [6] apply. 
Additionlly the following definition is needed: 

Shortcode: a short telephone number usually 4 to 6 digits long, this is represented by the 'tel:' UPJ defined in [6]. 
Whitespace: see definition for CFWS as defined in RFC2822 [9]. 

3.2 Abbreviations 

For the purposes of the present document, the abbreviations given in 3GPP TS 29.199-1 [6] and the following apply: 

EMS Enhanced Messaging Service 

IM Instant Messaging 

MMS Multimedia Messaging Service 

MMS-C Multimedia Messaging Service - Centre 

SMS Short Message Service 



Detailed service description 



Currently, in order to programmatically receive and send Multimedia Messages, it is necessary to write applications 
using specific protocols to access MMS functions provided by network elements (e.g. MMS-C). This approach requires 
application developers to have a high degree of network expertise. 

This contribution defines a Multimedia Messaging Web Service that can map to SMS, EMS, MMS, IM, E-mail, etc. 

The choice is between defining one set of interfaces per messaging network or a single set common to all networks; 
e.g. we could define sendMMS, sendEMS, sendSMS, etc., or just use sendMessage. Although the more specific the API 
the easier it is to use, there are advantages to a single set of network-neutral APIs. These advantages include: 

• improved service portability; 

• lower complexity, by providing support for generic user terminal capabilities only. 

For this version of the Parlay X specification, we provide sets of interfaces for two messaging Web Services: Short 
Messaging (part 7) and Multimedia Messaging (this part), which provides generic messaging features (including SMS). 

Multimedia Messaging provides operations (see clause 8.1, SendMessage API) for sending a Multimedia message to the 
network and a polling mechanism for monitoring the delivery status of a sent Multimedia message. It is expected that a 
future release of this specification will also provide an asynchronous notification mechanism for delivery status. 

Multimedia Messaging also allows an application to receive Multimedia messages. Both a polling (see clause 8.2, 
ReceiveMessage API) and an asynchronous notification mechanism (see clause 8.3, Message Notification API) are 
available. 

Figure 1 shows an example scenario using sendMessage and getMessageDeliveryStatus to send data to subscribers and 
to determine if the data has been received by the subscriber. The application invokes a Web Service to retrieve a stock 
quote (1) and (2) and sends the current quote - sendMessage - using the Parlay X Interface (3) of the Multimedia 
Messaging Web Service. After invocation, the Multimedia Message Web Service sends the message to an MMS-C 
using the MM7 interface (4) for onward transmission (5) to the subscriber over the Mobile network. 

Later, when the next quote is ready, the application checks to see - getMessageDeliveryStatus - if the previous quote has 
been successfully delivered to the subscriber. If not, it may for instance perform an action (not shown) to provide a 
credit for the previous message transmission. This way, the subscriber is only charged for a stock quote if it is delivered 
on time. 
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User 
profile 



Figure 1: Multimedia Messaging Scenario 



Namespaces 



The SendMessage interface uses the namespace: 

http://www.csapi.org/wsdl/parlayx/multimedia_messaging/send/v2_2 
The ReceiveMessage interface uses the namespace: 

http://www.csapi.org/wsdl/parlayx/multimedia_messaging/receive/v2_2 
The MessageNotification interface uses the namespace: 

http://www.csapi.org/wsdl/parlayx/multimedia_messaging/notification/v2_2 
The MessageNotificationManager interface uses the namespace: 

http://www.csapi.org/wsdl/parlayx/multimedia_messaging/notification_manager/v2_3 
The data types are defined in the namespace: 

http://www.csapi.org/schema/parlayx/multimedia_messaging/v2_2 

The 'xsd' namespace is used in the present document to refer to the XML Schema data types defined in 
XML Schema [5]. The use of the name 'xsd' is not semantically significant. 
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Sequence diagrams 



6.1 Send picture 



With the advent of picture capable phones, the exchange of photos to mobile phones is becoming more common place. 
This sequence diagram shows an application where a person can send a picture from an online photo album to a mobile 
phone. 



End User 



: Online Photo 



Album 



User logs on 



User selects photo to sen< 



Jser fills in send informatioln 



: Send MMS 
Web Service 



Send multimedia message 



Message identifier 



Get message status 



Short wait l\ 



^ 



Status 



Acknowledgement pager 



Figure 2 
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7 XML schema data type definition 

7.1 DeliveryStatus enumeration 

List of delivery status values. 



Enumeration 


Description 


Delivered 


Successful delivery. 


DeliveryUncertain 


Delivery status unknown: e.g. because it was handed off to another network. 


Deliverylmpossibl 
e 


Unsuccessful delivery; the message could not be delivered before it expired. 


MessageWaiting 


The message is still queued for delivery. This is a temporary state, pending transition to one of the 
preceding states. 



7.2 MessagePriority enumeration 



List of delivery priority values. 



Enumeratio 
n 


Description 


Default 


Default message 
priority 


Low 


Low message priority 


Normal 


Normal message 
priority 


High 


High message priority 



7.3 Deliverylnformation structure 



Delivery status information. 



Element 
name 


Element 
type 


Option 
al 


Description 


address 


xsd:anyURI 


No 


Address associated with the delivery status. The address field is coded as a 
URI. 


deliveryStatus 


DeliveryStatu 
s 


No 


Parameter indicating the delivery status. 
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7.4 Message Reference structure 

Message information. 



Element name 


Element type 


Option 
al 


Description 


messageldentifi 
er 


xsd:string 


Yes 


If present, contains a reference to a message stored in the Parlay X 
gateway. If the message is pure text, this parameter is not present. 


messageService 

ActivationNumb 

er 


xsd:string 


No 


Number associated with the invoked Message service, i.e. the 
destination address used by the terminal to send the message. 


senderAddress 


xsd:anyURI 


No 


Indicates message sender address. 


subject 


xsd:string 


Yes 


If present, indicates the subject of the received message. This 
parameter will not be used for SMS services. 


priority 


MessagePriorit 

y 


No 


The priority of the message: default is Normal. 


message 


xsd:string 


Yes 


If present, then the messageldentifier is not present and this 
parameter contains the whole message. The type of the message is 
always pure ASCII text in this case. The message will not be stored in 
the Parlay X gateway. 



7.5 MessageURI structure 



Message location information. 



Element 
name 


Element type 


Option 
al 


Description 


bodyText 


xsd:string 


Yes 


Contains the message body if it is encoded as ASCII text. 


fileReference 
s 


xsd:anyURI 
[0.. unbounded] 


Yes 


This is an array of URI references to all the attachments in the 
Multimedia message. These are URIs to different files, e.g. GIF 
pictures or pure text files. 



8 



Web Service interface definition 



8.1 Interface: SendMessage 

Operations to send messages and check status on sent messages. 

8.1.1 Operation: SendMessage 

Request to send a Message to a set of destination addresses, returning a requestldentifier to identify the message. The 
requestldentifier can subsequently be used by the application to poll for the message status, i.e. using 
getMessageDeliveryStatus to see if the message has been delivered or not. The content is sent as a Attachment as 
specified in SOAP Messages with Attachments [7]. 

Addresses may include group URIs as defined in the Address List Management specification. If groups are not 
supported, a PolicyException (POL0006) will be returned to the application. 
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8.1.1.1 



Input message: SendMessageRequest 



Part name 


Part type 


Option 
al 


Description 


Addresses 


xsd:anyURI [1.. unbounded] 


No 


Destination addresses for the Message. 


SenderAddres 
s 


xsd:string 


Yes 


Message sender address. This parameter is not allowed for 
all 3 rd party providers. Parlay X server needs to handle this 
according to a SLA for the specific application and its use 
can therefore result in a PolicyException. 


Subject 


xsd:string 


Yes 


Message subject. If mapped to SMS this parameter will be 
used as the senderAddress, even if a separate 
senderAddress is provided. 


Priority 


MessagePriority 


Yes 


Priority of the message. If not present, the network will 
assign a priority based on an operator policy. 


Charging 


Common:Charginglnformatio 
n 


Yes 


Charging to apply to this message. 



NOTE: The input message may also contain attachments, with appropriate content as defined by SOAP Messages 
with Attachments [7]. 



8.1.1.2 



Output message: SendMessageResponse 



Part name 


Part 
type 


Option 
al 


Description 


Requestldentifi 
er 


xsd:strin 

g 


No 


It is a correlation identifier that is used in a getMessageDeliveryStatus 
message invocation, i.e. to poll for the delivery status of all of the sent 
Messages. 



8.1.1.3 Referenced faults 

ServiceException from [6]: 

• SVC0001 - Service error. 

• SVC0002 - Invalid input value. 

• SVC0004 - No valid addresses. 

• SVC0006 - Invalid group. 
PolicyException from [6]: 

• POL0001 - Policy error. 

• POL0006 - Groups not allowed. 

• POL0007 - Nested groups not allowed. 

• POL0008 - Charging not supported. 

8.1.2 Operation: GetMessageDeliveryStatus 

This is a poll method used by the application to retrieve delivery status for each message sent as a result of a previous 
sendMessage message invocation. The requestldentifier parameter identifies this previous message invocation. 



8.1.2.1 



Input message: GetMessageDeliveryStatusRequest 



Part name 


Part 
type 


Option 
al 


Description 


Requestldentifi 
er 


xsd:strin 

g 


No 


Identifier related to the delivery status 
request. 
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8.1.2.2 



Output message: GetMessageDeliveryStatusResponse 



Part name 


Part type 


Option 
al 


Description 


DeliveryStatu 
s 


Deliverylnformation 
[0.. unbounded] 


Yes 


It is an array of status of the messages that were previously sent. 
Each array element represents a sent message: i.e. its 
destination address and its delivery status. 



8.1.2.3 Referenced faults 

ServiceException from [6]: 

• SVC0001 - Service error. 

• SVC0002 - Invalid input value. 
PolicyException from [6]: 

• POL0001 - Policy error. 

8.2 Interface: ReceiveMessage 

Operations to retrieve messages that have been received. 

8.2.1 Operation: GetReceivedMessages 

This method enables the application to poll for new messages associated with a specific registrationldentifier. If the 
registrationldentifier is not specified, the Parlay X server will return references to all messages sent to the application. 
The process of binding different registrationldentifier parameters to applications is an off-line process. The Parlay X 
gateway shall not allow an application to poll for messages using registrationldentifier parameters that are not 
associated with the application. The priority parameter may be used by the application to retrieve references to higher 
priority messages, e.g. if Normal is chosen only references to high priority and normal priority messages are returned. If 
the priority parameter is omitted all message references are returned. 



8.2.1.1 



Input message: GetReceivedMessagesRequest 



Part name 


Part type 


Option 
al 


Description 


Registrationldentifi 
er 


xsd:string 


No 


Identifies the off-line provisioning step that enables the application to 
receive notification of Message reception according to specified 
criteria. 


Priority 


MessagePriorit 

y 


Yes 


The priority of the messages to poll from the Parlay X gateway. All 
messages of the specified priority and higher will be retrieved. If not 
specified, all messages shall be returned, i.e. the same as specifying 
Low. 



8.2.1.2 



Output message: GetReceivedMessagesResponse 



Part 
name 


Part type 


Option 
al 


Description 


Message 
s 


MessageReference 
[0.. unbounded] 


Yes 


It contains an array of messages received according to the 
specified filter of registrationldentifier and priority. 



8.2.1.3 Referenced faults 

ServiceException from [6]: 
• SVC0001 - Service error. 
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• SVC0002 - Invalid input value. 
PolicyException from [6]: 

• POL0001 - Policy error. 

8.2.2 Operation: GetMessageURIs 

This method will read the different parts of the message, create local files in the Parlay Gateway and return URI 
references to them. The application can then simply read each file or just have them presented as links to the end-user. 
The URIs to the files will be active for an agreed time. 



8.2.2.1 



Input message: GetMessageURIsRequest 



Part name 


Part 
type 


Option 
al 


Description 


MessageRefldentifi 
er 


xsd:strin 

g 


No 


The identity of the message to 
retrieve. 



8.2.2.2 



Output message: GetMessageURIsResponse 



Part 
name 


Part type 


Option 
al 


Description 


Messag 
e 


MessageU 
Rl 


No 


It contains the complete message, i.e. the textual part of the message, if such 
exists, and a list of file references for the message attachments, if any. 



8.2.2.3 Referenced faults 

ServiceException from [6]: 

• SVC0001 - Service error. 

• SVC0002 - Invalid input value. 
PolicyException from [6]: 

• POL0001 - Policy error. 

8.2.3 Operation: GetMessage 

This method will read the whole message. The data is returned as an attachment, as defined in SOAP Messages with 
Attachments [7], in the return message. 



8.2.3.1 



Input message: GetMessageRequest 



Part name 


Part 
type 


Option 
al 


Description 


MessageRefldentifi 
er 


String 


No 


The identity of the 
message 



8.2.3.2 



Output message: GetMessageResponse 



Part 
name 


Part 
type 


Option 
al 


Descriptio 
n 


None 
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8.2.3.3 Referenced faults 

ServiceException from [6]: 

• SVC0001 - Service error. 

• SVC0002 - Invalid input value. 
PolicyException from [6]: 

• POL0001 - Policy error. 

8.3 Interface: MessageNotification 

MessageNotification is the application side notification interface to which multimedia messages are delivered. 

8.3.1 Operation: NotifyMessage Reception 

The notification is used to send a multimedia message to the application. The notification will occur only if the 
multimedia message fulfils the criteria specified when starting the multimedia message notification. 



8.3.1.1 



Input message: NotifyMessageReceptionRequest 



Part 
name 


Part type 


Option 
al 


Description 


correlator 


xsd:string 


No 


Correlator provided in request to set up this notification 


Message 


MessageReferenc 
e 


No 


This parameter contains all the information associated with the received 
message. 



8.3.1.2 



Output message: NotifyMessageReception Response 



Part 
name 


Part 
type 


Option 
al 


Descriptio 


None 









8.3.1.3 

None. 



Referenced faults 



8.4 Interface: MessageNotificationManager 

The multimedia message notification manager enables applications to set up and tear down notifications for multimedia 
messages online. The means to provision notifications offline are not specified here. 

8.4.1 Operation: StartMessageNotification 

Start notifications to the application for a given Message Service activation number and criteria. 

The Message Service activation number is an Address Data item as defined in 3GPP TS 29.199-1 [6]. A Shortcode is an 
example of an Address Data item. 

The correlator provided in the reference must be unique for the application Web Service at the time the notification is 
initiated, otherwise a ServiceException (SVC0005) will be returned to the application.. 

If specified, criteria will be used to filter messages that are to be delivered to an application. If criteria are not provided, 
or is an empty string, then all messages for the MessageServiceActivationNumber will be delivered to the application. 
The MessageServiceActivationNumber and criteria combination must be unique. If a criteria overlaps then S VC0008 
will be returned to the application and the notification will not be set up. Note that the use of criteria will allow different 
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notification endpoints to receive notifications for the same MessageServiceActivationNumber. The combination of 
MessageServiceActivationNumber and criteria must be unique, so that a notification will be delivered to only one 
notification endpoint. If no match is found, the message will not be delivered to the application. 



8.4.1.1 



Input message: StartMessageNotification Request 



Part name 


Part type 


Optional 


Description 


Reference 


common:SimpleReference 


No 


Notification endpoint definition 


MessageServiceActivationNumber 


xsd:anyURI 


No 


the destination address of the multimedia 
message 


Criteria 


xsd:string 


Yes 


The text to match against to determine the 
application to receive the notification. 
This text is matched agains the first word, 
as defined as the initial characters after 
discarding any leading Whitespace and 
ending with a Whitespace or end of the 
string. The matching shall be case- 
insensitive. 

If the subject of the multimedia message 
is present it shall be used as the string, if 
not the string is defined as the first 
plain/text part of the content (see 3GPP 
TS 23.140 [8]). 



8.4.1.2 



Output message: StartMessageNotification Response 



Part Name 


Part Type 


Optional 


Description 


none 









8.4.1.3 Referenced Faults 

ServiceException from [6] 

• SVC0001 - Service error 

• SVC0002 - Invalid input value 

• SVC0005 - Duplicate correlator 

• SVC0008 - Overlapping Criteria 
PolicyException from [6] 

• POL000 1 - Policy error 

8.4.2 Operation: StopMessageNotification 

The application may end a multimedia message notification using this operation 



8.4.2.1 



Input message: StopMessageNotification Request 



Part name 


Part type 


Optional 


Description 


Correlator 


xsd:string 


No 


Correlator of request to end 



8.4.2.2 



Output message: StopMessageNotification Response 



Part Name 


Part Type 


Optional 


Description 


None 
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8.4.2.3 Referenced Faults 

ServiceException from [6] 

• SVC0001 - Service error 

• SVC0002 - Invalid input value 
PolicyException from [6] 

• POL000 1 - Policy error 



9 Fault definitions 

9.1 ServiceException 
9.1.1 Void 

The fault code (SVC0230) is reserved and shall not be used. 



10 Service policies 



Table: Service policies for this service 



Name 


Type 


Description 


GroupSupport 


xsd:Boolean 


Groups may be included with addresses 


NestedGroupSupport 


xsd:Boolean 


Are nested groups supported in group definitions 


ChargingSupported 


xsd:Boolean 


Charging supported for send message operation 
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Annex A (normative): 

WSDL for Multimedia Messaging 



The document/literal WSDL representation of this interface specification is compliant to 3GPP TS 29.199-1 [6] and is 
contained in text files (contained in archive 29199-05-630-doclit.zip) which accompanies the present document. 
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Annex B (informative); 
Change history 



Change history 


Date 


TSG# 


TSG Doc. 


CR 


Rev 


Subject/Comment 


Old 


New 


Dec 2003 


CN 21 


NP-030552 


-- 


-- 


Submitted to CN#22 for Information 


1.0.0 




Jan 2004 










Added The W3C WSDL representation of the APIs specified in the 
present document is contained in a set of files which accompany the 
present document: 

px0326rpcenc.zip 

px0326rpclit.zip 


1.0.1 




Jun 2004 


CN_24 


NP-040274 


— 


— 


Split into multi-part specification. 29.199-0n, for n=1,2...9. 
Submitted to CN#24 for Information 


1.0.3 




Sep 2004 


CN 25 


NP-040360 


-- 


-- 


Draft v200 submitted to TSG CN#25 for Approval. 


2.0.0 


6.0.0 


Dec 2004 


CN_26 


NP-040487 


001 


— 


Add MessageNotificationManager interface to PXWS Multimedia- 
Messaging 


6.0.0 


6.1.0 


Mar 2005 


CN 27 


NP-050021 


002 


-- 


Correct criteria 


6.1.0 


6.2.0 


Mar 2005 


CN 27 


NP-050021 


003 


-- 


Fix StopMessageNotification message part 


6.1.0 


6.2.0 


Jun 2005 


CT 28 


CP-050221 


0004 


-- 


Optionals for Part 5 


6.2.0 


6.3.0 
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Document history 


V6.1.0 


December 2004 


Publication 


V6.2.0 


March 2005 


Publication 


V6.3.0 


June 2005 


Publication 
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